Add Profiles concepts page by christos68k · Pull Request #9339 · open-telemetry/opentelemetry.io

christos68k · 2026-03-05T13:15:50Z

I have read and followed the Contributing docs, especially the "First-time contributing?" section.
This PR has content that I did not fully write myself.
- I used AI and I have read and followed the Generative AI Contribution Policy.
I have the experience and knowledge necessary to understand, review, and validate all content in this PR.¹

Summary

Added a Profiles concepts page to set the context and provide a high-level introduction to OpenTelemetry profiling (links to OTel eBPF profiler and specification for more information)
Modified concepts index page to link to the Profiles concepts page

I took the Profiles overview from the current Profiles spec README and blended it into this PR. I did that as it doesn't really fit in the spec README and the high-level description it provides is much more suitable for the concepts page. I will subsequently open another PR to update and extend the Profiles spec page.

CC: @theletterf @open-telemetry/profiling-maintainers @open-telemetry/profiling-approvers

Yes, I can answer maintainer questions about the content of this PR, without using AI. ↩

This is a high-level introduction to OpenTelemetry profiles, setting the context and linking to the OTel eBPF profiling agent and the specification.

Now points to Profiles concepts page.

christos68k · 2026-03-05T13:18:18Z

+Additional language-specific profiling integrations that tap into built-in
+runtime profiling frameworks (e.g. JFR for Java, pprof for Go) will also become
+available as the signal matures.


CC: @jhalliday Feel free to add extra information here.

I think that's fine for now. I'm maintaining https://docs.google.com/document/d/1hrfElwEdoUQbj-fY0vVVN7kmWmlmn9F_eZzxMuVnVwo/edit?usp=sharing but it's not targeted at end-users. Once the OTel Java SDK has support shipping I'll do user docs for that and update to link from here I think.

christos68k · 2026-03-05T13:19:15Z

+Profiles are emerging as the fourth essential signal of observability, alongside
+logs, metrics, and traces. They offer unparalleled insights into system and
+application behavior, often uncovering performance bottlenecks overlooked by
+other signals.
+
+Profiles provide granular, time-based views of resource consumption and code
+execution, encompassing:
+
+- **Application-level profiling**: Reveals how software functions consume CPU,
+  memory, and other resources, highlighting slow or inefficient code.
+
+- **System-level profiling**: Offers a holistic view of the infrastructure,
+  pinpointing issues in operating system calls, kernel operations, and I/O.


I took this from the existing Profiles spec page as I think it provides better value here. I'll subsequently open a spec PR to update the Profiles spec pages.

theletterf

Good work. Any chance we could show what the profiling payload looks like?

theletterf · 2026-03-06T14:24:18Z

+
+OpenTelemetry provides an
+[eBPF-based profiling agent](https://github.com/open-telemetry/opentelemetry-ebpf-profiler)
+for Linux, capable of profiling most languages with zero code changes.


Suggested change

for Linux, capable of profiling most languages with zero code changes.

for Linux, capable of profiling most languages with zero-code changes.

Are you sure about this? zero-code reads strange in this sentence (maybe it's fine if used as an adjective e.g. zero-code instrumentation).

If you prefer, I can reword this to "without any code changes"

See fa5a813

Review feedback Co-authored-by: Fabrizio Ferri-Benedetti <fabri.ferribenedetti@elastic.co>

christos68k · 2026-03-06T14:37:36Z

Good work. Any chance we could show what the profiling payload looks like?

If you mean in terms of protobuf representation, I think it's best if we do this in the Profiles spec (where I'm working on two pages: README and data model that will present the format in detail). Trying to keep the concepts page more high-level, to serve as an introduction to OTel Profiles and give all relevant introductory context.

svrnm · 2026-03-09T08:09:31Z

@open-telemetry/profiling-approvers can we get a 👍 from one more profiling approver/maintainer, then this is probably good to go:)

theletterf · 2026-03-10T07:49:31Z

/fix:format

otelbot-docs · 2026-03-10T07:52:07Z

✅ fix:format applied successfully in run 22892412317.

christos68k added 3 commits March 5, 2026 07:40

Add profiles concepts page

aabc1b5

This is a high-level introduction to OpenTelemetry profiles, setting the context and linking to the OTel eBPF profiling agent and the specification.

Update link to Profiles

62cfba5

Now points to Profiles concepts page.

Apply test-and-fix

2be092b

christos68k requested a review from a team as a code owner March 5, 2026 13:15

github-project-automation Bot added this to SIG Comms: PRs & Issues Mar 5, 2026

otelbot-docs Bot added the missing:docs-approval Co-owning SIG has provided approval, PR needs approval from docs maintainer label Mar 5, 2026

christos68k commented Mar 5, 2026

View reviewed changes

christos68k mentioned this pull request Mar 5, 2026

Add documentation for Profiling #7874

Closed

3 tasks

theletterf self-assigned this Mar 5, 2026

theletterf added the sig:profiling label Mar 5, 2026

theletterf approved these changes Mar 6, 2026

View reviewed changes

otelbot-docs Bot added ready-to-be-merged This PR is ready to be merged by a maintainer and removed missing:docs-approval Co-owning SIG has provided approval, PR needs approval from docs maintainer labels Mar 6, 2026

christos68k and others added 3 commits March 6, 2026 15:32

Update content/en/docs/concepts/signals/profiles.md

a1118fa

Review feedback Co-authored-by: Fabrizio Ferri-Benedetti <fabri.ferribenedetti@elastic.co>

Update content/en/docs/concepts/signals/profiles.md

20ccfce

Review feedback Co-authored-by: Fabrizio Ferri-Benedetti <fabri.ferribenedetti@elastic.co>

Update content/en/docs/concepts/signals/profiles.md

6c21a79

Review feedback Co-authored-by: Fabrizio Ferri-Benedetti <fabri.ferribenedetti@elastic.co>

Review feedback

fa5a813

jhalliday approved these changes Mar 9, 2026

View reviewed changes

Merge branch 'main' into ck/profiles-concepts

17a175c

theletterf enabled auto-merge March 10, 2026 07:50

Results from /fix directive

98f324b

theletterf added this pull request to the merge queue Mar 10, 2026

Merged via the queue into open-telemetry:main with commit 274bf95 Mar 10, 2026
23 checks passed

github-project-automation Bot moved this to Done in SIG Comms: PRs & Issues Mar 10, 2026

christos68k mentioned this pull request Mar 11, 2026

Concepts are missing from the concept section #7280

Closed

	for Linux, capable of profiling most languages with zero code changes.
	for Linux, capable of profiling most languages with zero-code changes.

Uh oh!

Conversation

christos68k commented Mar 5, 2026

Summary

Footnotes

Uh oh!

christos68k Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

jhalliday Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

christos68k Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

theletterf left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

theletterf Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

christos68k Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

christos68k Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

christos68k commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

svrnm commented Mar 9, 2026

Uh oh!

theletterf commented Mar 10, 2026

Uh oh!

otelbot-docs Bot commented Mar 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

christos68k Mar 5, 2026 •

edited

Loading

christos68k commented Mar 6, 2026 •

edited

Loading